[PB Generic Table][C++ SDK] Traverse Table Data
1. Interface Description
The traverse interface is used to traverse the full table (example path: examples/tcaplus/C++_pb2_asyncmode_simpletable/SingleOperation/traverse)
Note:
- Each table can only have one traverser running at the same time. A single gamesvr supports up to 8 traversers at the same time. It is recommended to reduce the number of traversers, otherwise the normal read/write access delay will be affected.
2. Version Requirements
SDK of version 3.55.0 or above
3. Preparations
Refer to Preparation document to complete the preparation before using this interface, create the following PB Generic table, and use the PB tool to convert the table into C++ code.
syntax = "proto2";
package myTcaplusTable;
import "tcaplusservice.optionv1.proto";
message tb_online {
option(tcaplusservice.tcaplus_primary_key) = "openid,tconndid,timekey";
required int32 openid = 1; //QQ Uin
required int32 tconndid = 2;
required string timekey = 3;
required string gamesvrid = 4;
optional int32 logintime = 5 [default = 1];
repeated int64 lockid = 6 [packed = true]; //The repeated type field is decorated with the packed keyword
optional pay_info pay = 7;
message pay_info {
optional uint64 total_money = 1;
optional uint64 pay_times = 2;
}
}
Get the following information after the preparation. These details will be used by the SDK:
- Directory server address list
- App ID
- App access password
- Game zone ID
- Table name
4. Example Code
4.1 Example Code for Asynchronous Call
Basic execution process of example code:
- Define table configuration parameters;
- Create a client;
- Define a callback function to process the response;
- Send a request;
- example framework;
Steps 1, 2 and 5 are common codes for all examples, focusing on sending requests and the callback function for response processing in steps 3 and 4
4.1.1 Define table configuration parameters (code path: examples/tcaplus/C++_common_for_pb/common.h)
It mainly sets the configuration parameters of the table, which are located in the header of the code file
// Tcapdir address of the target app
static const char DIR_URL_ARRAY[][TCAPLUS_MAX_STRING_LENGTH] =
{
"tcp://10.191.***.99:9999"
};
// Number of tcapdir addresses of the target app
static const int32_t DIR_URL_COUNT = 1;
// Set ID of the target app
static const int32_t APP_ID = 3;
// Table group ID of the target app
static const int32_t ZONE_ID = 1;
// App password of the target app
static const char * SIGNATURE = "*******";
// Table name of the target app: tb_online
static const char * TABLE_NAME = "tb_online";
4.1.2 Create a SDK Client (code path: examples/tcaplus/C++_common_for_pb/common.h)
Create a log handle through the log configuration file tlogconf.xml for SDK log printing; Create a Tcaplus client through this code. This client is only allowed to be used by a single thread. The multi-threading model can initialize a client instance on each thread
//Tcaplus PB API client
TcaplusAsyncPbApi g_stAsyncApi;
int32_t InitAsyncPbApi()
{
//PB API configuration
ClientOptions cfg;
cfg.app_id = APP_ID;
cfg.zones.push_back(ZONE_ID);
strcpy(cfg.signature, SIGNATURE);
for (int32_t i = 0; i < DIR_URL_COUNT; i++)
{
cfg.dirs.push_back(DIR_URL_ARRAY[i]);
}
//PB table accessed
cfg.tables.push_back(TABLE_NAME);
//Log configuration
strncpy(cfg.log_cfg, "tlogconf.xml", sizeof(cfg.log_cfg));
//Initialization connection timeout 5s
cfg.timeout = 5000;
//Initialization connection
int32_t iRet = g_stAsyncApi.Init(cfg);
if (0 != iRet)
{
cout << "ERROR: g_stAsyncApi.Init failed, log cfg: " << cfg.log_cfg << ", iRet: " << iRet << "." << endl;
return iRet;
}
return iRet;
}
4.1.3 Define a callback function to process the response (code path: examples/tcaplus/C++_pb2_asyncmode_simpletable/SingleOperation/traverse/main.cpp)
class CommonCallback : public TcaplusPbCallback
{
public:
CommonCallback()
{
cout << "Init CommonCallback." << endl;
}
~CommonCallback()
{
cout << "Fini ~CommonCallback." << endl;
}
int OnRecv(const std::vector< ::google::protobuf::Message *> &msgs)
{
for (size_t idx = 0; idx < msgs.size(); idx++)
{
tb_online* t = dynamic_cast<tb_online *>(msgs[idx]);
if (NULL == t)
{
cout << "ERROR: msgs[" << idx << "] not tb_online type." << endl;
return -1;
}
cout << "---------- receive a response----------:" << endl;
cout << "openid=" << t->openid() << endl;
cout << "tconndid=" << t->tconndid() << endl;
cout << "timekey=" << t->timekey() << endl;
cout << "gamesvrid=" << t->gamesvrid() << endl;
cout << "logintime=" << t->logintime() << endl;
for (int32_t i = 0; i < t->lockid_size();i++)
{
cout << "lockid[" << i << "]=" << t->lockid(i) << endl;
}
tb_online_pay_info pay = t->pay();
cout << "pay total_money=" << pay.total_money() << "; pay_times=" << pay.pay_times() << endl;
std::string version;
int iRet = g_stAsyncApi.GetMessageOption(*t, NS_TCAPLUS_PROTOBUF_API::MESSAGE_OPTION_DATA_VERSION, &version);
cout << "after GetMessageOption iRet= [" << iRet << "] version:" << version.c_str() << " msg:" << t << endl;
}
return 0;
}
int OnError(const std::vector< ::google::protobuf::Message *> &msgs, int errorcode)
{
if (TcapErrCode::API_ERR_NO_MORE_RECORD == errorcode)
{
g_dwTotalRevNum=1;
cout << "NO MORE RECORDS, FINISH" << endl;
}
else
{
cout << "encountering error" << endl;
}
return 0;
}
int OnFinish(const NS_TCAPLUS_PROTOBUF_API::MsgParam ¶m)
{
cout << "OnFinish: " << param.m_nOperation << " req: " << param.m_vecMsgs.size()<< endl;
return 0;
}
};
4.1.4 Send a request (code path: examples/tcaplus/C++_pb2_asyncmode_simpletable/SingleOperation/traverse/main.cpp)
Send requests using the client
void SendTraverseRequest(struct schedule * S, void* arg)
{
static tb_online t;
static CommonCallback cb;
int32_t iRet = g_stAsyncApi.Traverse(&t, &cb);
if (iRet != TcapErrCode::GEN_ERR_SUC)
{
cout << "ERROR: Traverse Error iRet = " << iRet << endl;
}
}
4.1.5 Example asynchronous framework (code path: examples/tcaplus/C++_common_for_pb/common.h)
The proc main framework calls the corresponding functions to send requests, receive responses, and handle timeouts by implementing the three function pointers of the callback function. All examples of this framework are common
int32_t main(int32_t argc, char* argv[])
{
int32_t iRet = 0;
//Initialization
iRet = InitAsync("tlogconf.xml");
if (0 != iRet)
{
cout << "ERROR: Init failed, iRet: " << iRet << ", please check the tcaplus_pb.log for detail." << endl;
return iRet;
}
//Initialization
g_stPbCallbackFunctions.pfnSendRequest = SendTraverseRequest;
iRet = ProcAsync();
if (0 != iRet)
{
cout << "ERROR: ProcAsync failed, iRet: " << iRet << ", please check the tcaplus_pb.log for detail." << endl;
return iRet;
}
FinishAsync();
return 0;
}
// Initialize pb api
int32_t InitAsync(const char* log_conf)
{
int32_t iRet = 0;
iRet = InitAsyncPbApi(log_conf);
if (0 != iRet)
{
cout << "ERROR: InitCoroutinePbApi failed, iRet: " << iRet << "." << endl;
return iRet;
}
return iRet;
}
//************************************************************************
// Method: FinishAsync
// Returns:
// Qualifier: Processing logic on function exit
//*************************************************************************/
void FinishAsync()
{
cout << "g_stAsyncApi finish!" << endl;
g_stAsyncApi.Fini();
google::protobuf::ShutdownProtobufLibrary();
}
//************************************
// Method: ProcAsync
// Returns: int32_t
// Qualifier: Processing function
//************************************
int32_t ProcAsync()
{
int32_t iRet = 0;
// The variable iSendRequestCount used in this sample is to control the number of packages
int32_t iSendRequestCount = 0;
do
{
if (iSendRequestCount < TOTAL_SEND_RECV_NUM)
{
if(NULL == g_stPbCallbackFunctions.pfnSendRequest)
{
cout << "ERROR: g_stPbCallbackFunctions.pfnSendRequest is NULL, so will finish example." << endl;
break;
}
int32_t iUin = iSendRequestCount;
g_stPbCallbackFunctions.pfnSendRequest(NULL, (void *)&iUin);
iSendRequestCount++;
}
// Update and receive the response package
g_stAsyncApi.UpdateNetwork();
usleep(TCAPLUS_SLEEEP_US);
} while (g_dwTotalRevNum != TOTAL_SEND_RECV_NUM);
cout << "end mytest, please check the mytest.log for detail." << endl;
return 0;
}
5. The main interfaces of TcaplusAsyncPbApi are described as follows:
class TcaplusAsyncPbApi
{
public:
TcaplusAsyncPbApi();
virtual ~TcaplusAsyncPbApi();
/**
* @brief: initialization operation
*
* @param [IN] option: option information
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful.
*/
int Init(NS_TCAPLUS_PROTOBUF_API::ClientOptions& option);
/**
* @brief: switch the zone of the current operation (table group)
*
* @param [IN] zone_id: zone (table group) ID
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful.
*/
int SelectZone(uint32_t zone_id);
/**
* @brief: event loop, receive and send packages through the network, driving the operation of the entire API
*
* @retval >0: receive packages
* @retval 0: normal.
* @retval <0: abnormal.
*/
int UpdateNetwork();
/**
* Options for setting messages
* The value of item can be taken as follows:
* a). MESSAGE_OPTION_VERSION_CHECK=1, set the record version check in the API
* The option value includes "1": enable version comparison (default)
* "2": disable version check and force the server to write the record version specified by MESSAGE_OPTION_DATA_VERSION
* "3": do not check the record version, but increase the server version
* b).MESSAGE_OPTION_DATA_VERSION = 2, set the record version function in the API
* The option value is a string that corresponds to the expected record version, such as "10," which means that the record version is 10
* c).MESSAGE_OPTION_ASYNC_ID = 3, set the message asynchronous ID in the API. It is a uint64 string
* The option value is a string that corresponds to the expected asynchronous ID, such as "13," which means that the asynchronous ID is 13
* d).MESSAGE_OPTION_MESSAGE_INVALID = 4, set the message invalid (valid after sending the request and before the message returns)
* The option value is a string that corresponds to the expected asynchronous ID, such as "13," which means that the asynchronous ID is 13. If it is not set, it is null
* e).MESSAGE_OPTION_MESSAGE_AUTO_RELEASE = 5, set the message auto release in the API (valid in asynchronous mode) (not recommended)
* f).MESSAGE_OPTION_USER_BUFF = 6, set the user-defined binary data passed in by the user in the API, with a maximum length of 1024 bytes
* g).MESSAGE_OPTION_CALLBACK_AUTO_RELEASE = 7, set the callback auto release in the API (valid in asynchronous mode) (not recommended)
* h).MESSAGE_OPTION_ENABLE_INCREASE_NOT_EXIST = 8, set allowing FieldInc to create records when they do not exist, which increase based on the default value. The value 0 means not allowed, and the value 1 means allowed
* i).MESSAGE_OPTION_ENABLE_SET_NOT_EXIST = 9, set allowing FieldSet to create records when they do not exist, which are increased based on the default value. The value 0 means not allowed, and the value 1 means allowed
* j).MESSAGE_OPTION_RESULT_FLAG_FOR_SUCCESS = 10, result flag when the user explicit settings request is successfully executed, and will overwrite the default configuration of the API
* The option value includes "0": return whether the operation was successfully executed
* "1": return the data same with the request
* "2": return the latest data for all fields in the modified record
* "3": return the old data for all fields in the modified record
* k).MESSAGE_OPTION_RESULT_FLAG_FOR_FAIL = 11, result flag when the user explicit settings request fails to execute, and will overwrite the default configuration of the API
* The option value includes "0": return whether the operation was successfully executed
* "1": return the data same with the request
* "2": return the latest data for all fields in the modified record
* "3": return the old data for all fields in the modified record
*/
int SetMessageOption(const ::google::protobuf::Message &msg, int32_t item, const std::string &option); // Set reservation for subsequent parameters
/**
* Options for getting messages
* The value of item can be taken as follows:
* a). MESSAGE_OPTION_VERSION_CHECK=1, get the record version check option in the API
* The option return value includes "1": enable version check (default)
* "2": disable version check and force the server to write the record version number specified by MESSAGE_OPTION_DATA_VERSION
* "3": do not check the record version, but increase the server version
* b).MESSAGE_OPTION_DATA_VERSION = 2, get the record version option in the API
* The option return value is a string that corresponds to the record version set before, such as "10," which means that the record version is 10
* c).MESSAGE_OPTION_ASYNC_ID = 3, get the option to set the asynchronous ID in the API. It is a uint64 string
* The option return value is a string that corresponds to the asynchronous ID set before, such as "13," which means that the asynchronous ID is 13
* d).MESSAGE_OPTION_MESSAGE_INVALID = 4, get the option to set the message to be invalid
* e).MESSAGE_OPTION_MESSAGE_AUTO_RELEASE = 5, get the option to set the message auto release
* f).MESSAGE_OPTION_USER_BUFF = 6, get the user-defined binary data passed in by the user
* g).MESSAGE_OPTION_CALLBACK_AUTO_RELEASE = 7, set the callback auto release in the API (valid in asynchronous mode)
* h).MESSAGE_OPTION_ENABLE_INCREASE_NOT_EXIST = 8, set allowing FieldInc to create records when they do not exist, which increase based on the default value. The value 0 means not allowed, and the value 1 means allowed
* i).MESSAGE_OPTION_ENABLE_SET_NOT_EXIST = 9, set allowing FieldSet to create records when they do not exist, which are increased based on the default value. The value 0 means not allowed, and the value 1 means allowed
* j).MESSAGE_OPTION_RESULT_FLAG_FOR_SUCCESS = 10, get the result flag for success, which overwrites the default API configuration
* The option value includes "0": return whether the operation was successfully executed
* "1": return the data same with the request
* "2": return the latest data for all fields in the modified record
* "3": return the old data for all fields in the modified record
* k).MESSAGE_OPTION_RESULT_FLAG_FOR_FAIL = 11, get the result flag when a request for user explicit settings or API default configuration fails to execute
* The option value includes "0": return whether the operation was successfully executed
* "1": return the data same with the request
* "2": return the latest data for all fields in the modified record
* "3": return the old data for all fields in the modified record
*/
int GetMessageOption(const ::google::protobuf::Message &msg, int32_t item, std::string *option); // Set reservation for subsequent parameters, such as the record version
/**
* Get the message version
* > 0 success else: failed to get the version. There may be no version in the response message. You need to set the resultflag
*
*/
int32_t GetMessageVersion(const ::google::protobuf::Message &msg);
/**
* Options for deleting messages
* The value of item can be taken as follows:
* a). MESSAGE_OPTION_VERSION_CHECK=1, delete the record version check option in the API
* b).MESSAGE_OPTION_DATA_VERSION = 2, delete the record version option in the API
* c).MESSAGE_OPTION_ASYNC_ID = 3, delete the option to set the asynchronous ID in the API.
* d).MESSAGE_OPTION_MESSAGE_INVALID = 4, delete the option to set the message to be invalid
* e).MESSAGE_OPTION_MESSAGE_AUTO_RELEASE = 5, delete the option to set the message auto release
* f).MESSAGE_OPTION_USER_BUFF = 6, get the user-defined binary data passed in by the user
* g).MESSAGE_OPTION_CALLBACK_AUTO_RELEASE = 7, set the callback auto release in the API (valid in asynchronous mode)
* h).MESSAGE_OPTION_ENABLE_INCREASE_NOT_EXIST = 8, set allowing FieldInc to create records when they do not exist, which increase based on the default value. The value 0 means not allowed, and the value 1 means allowed
* i).MESSAGE_OPTION_ENABLE_SET_NOT_EXIST = 9, set allowing FieldSet to create records when they do not exist, which are increased based on the default value. The value 0 means not allowed, and the value 1 means allowed
*/
int DelMessageOption(const ::google::protobuf::Message &msg, int32_t item); // Set reservation for subsequent parameters
/**
* @brief: get the field value of the msg based on the key value in the msg entered by the user, and fill it in the msg.
*
* @param [INOUT] msg: the key value entered by the user and return the specified field to msg
* @param [INOUT] cb: message callback function
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful.
*/
int Get(::google::protobuf::Message *msg, TcaplusPbCallback *cb);
/**
* @brief: get the field value of the msg based on the key value in the msg entered by the user, and fill it in the msg.
*
* @param [INOUT] msg: the key value entered by the user and return the specified field to msg
*@param [IN] condition: filter condition
* @param [INOUT] cb: message callback function
* @retval COMMON_ERR_CONDITION_NOT_MATCHED: condition is not matched
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful.
*/
int Get(::google::protobuf::Message *msg, const std::string &condition, TcaplusPbCallback *cb);
/**
* @brief: get the values of multiple records through index and fill them into the vec structure of res based on the index name, msg value, offset and limit entered by the user in req, and return the total number of records and the remaining number of records.
*
* @param [INOUT] req: the req entered by the user
* @param [INOUT] res: the res entered by the user
* @param [INOUT] cb: message callback function
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful.
*/
int Get(NS_TCAPLUS_PROTOBUF_API::IndexGetRequest& req, TcaplusPbCallback *cb);
/**
* @brief: get the values of multiple records through index and fill them into the vec structure of res based on the index name, msg value, offset and limit entered by the user in req, and return the total number of records and the remaining number of records.
*
* @param [INOUT] req: the req entered by the user
* @param [INOUT] res: the res entered by the user
* @param [INOUT] cb: message callback function
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful.
*/
int Get(NS_TCAPLUS_PROTOBUF_API::GlobalIndexGetRequest& req, TcaplusPbCallback *cb);
/**
* @brief: get the field values of the msg in batch based on the key values in the msgs entered by the user, and fill it in msgs?
*
* @param [INOUT] msg: the list of key values entered by the user and return the specified field to msg
* @param [INOUT] cb: message callback function
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful. Only when at least one field is successfully queried will it return 0.
*/
int BatchGet(std::vector< ::google::protobuf::Message * > *msgs, TcaplusPbCallback *cb);
/**
* @brief: delete the record based on the msg entered by the user, and return the successfully deleted record to the user through the parameters of the OnRecv method in cb by default.
* The user can also set returning the existing data through the parameters of the OnError method in cb when the deletion fails through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_FAIL, "3").
* @note: only when the result is TcapErrCode::SVR_ERR_FAIL_INVALID_VERSION or other error codes indicating that the record already exists before the operation, will the existing data be returned. Otherwise, the value passed into OnError callback function is the msg pointer to the user request.
* The user can also set not returning the record when the deletion succeeds or fails through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_SUCCESS, "0") or SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_FAIL, "0").
*
* @param [IN] msg: msg of the data record to be deleted
* @param [INOUT] cb: message callback function
* @retval TXHDB_ERR_RECORD_NOT_EXIST: the record does not exist
* @retval < 0 failed and returned the corresponding error code.
* @retval = 0 operation successful
*/
int Del(::google::protobuf::Message *msg, TcaplusPbCallback *cb);
/**
* @brief: delete the record based on the msg entered by the user, and return the successfully deleted old record to the user through the parameter of the OnRecv method in cb by default.
* The user can also set returning the existing data through the parameters of the OnError method in cb when the deletion fails through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_FAIL, "3").
* @note: only when the result is TcapErrCode::SVR_ERR_FAIL_INVALID_VERSION or other error codes indicating that the record already exists before the operation, will the existing data be returned. Otherwise, the value passed into OnError callback function is the msg pointer to the user request.
* The user can also set not returning the record when the deletion succeeds or fails through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_SUCCESS, "0") or SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_FAIL, "0").
*
* @param [IN] msg: msg of the data record to be deleted
* @param [IN] condition: filter condition expression. The modification operation will only be executed if the condition is matched
* Currently only contains condition filtering is supported, and the expression is <repeated-field> contains(<condition-expr>)
* For example, "a.b.c contains ($>0)", where a.b.c is a basic type, and '$' is the field value
* For example, "a.b.c contains (x>0 AND y>0)", where a.b.c is a combination type, and 'x' is the basic field value in the combination type
* @param [INOUT] cb: message callback function
* @retval TXHDB_ERR_RECORD_NOT_EXIST: the record does not exist.
* @retval COMMON_ERR_CONDITION_NOT_MATCHED: condition is not matched, and the record will not be deleted.
* @retval <0 failed and returned the corresponding error code.
* @retval = 0 operation successful.
*/
int Del(::google::protobuf::Message *msg, const std::string &condition, TcaplusPbCallback *cb);
/**
* @brief: insert or update the record based on the msg entered by the user. If the record exists, update the specified record value. Otherwise, insert the specified record, and return the successfully operated record to the user through the parameter of the OnRecv method in cb by default.
* The user can determine whether it is an insert operation or update operation based on the record version. When version == 1 means that it is an insert operation, while version > 1 means that it is an update operation.
* The user can also set returning the data before the update through the parameters of the OnRecv method in cb when the operation succeeds through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_SUCCESS, "3").
* @note: the data before the update will only be returned when it is the actual update operation (that is, the record version in the callback function is greater than 1). Otherwise, the value passed into OnRecv callback function is the msg pointer to the user request.
* The user can also set returning the data before the update through the parameters of the OnError method in cb when the operation fails through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_FAIL, "3").
* @note: only when the result is TcapErrCode::SVR_ERR_FAIL_INVALID_VERSION or other error codes indicating that the record already exists before the operation, will the existing data be returned. Otherwise, the value passed into OnError callback function is the msg pointer to the user request.
* The user can also set returning the record when the operation succeeds or fails through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_SUCCESS, "0") or SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_FAIL, "0").
*
* @param [INOUT] msg: msg of the data record to be inserted or updated
* @param [INOUT] cb: message callback function
* @retval < 0 failed and returned the corresponding error code.
* @retval = 0 operation successful
*/
int Set(::google::protobuf::Message *msg, TcaplusPbCallback *cb);
/**
* @brief: insert or update the record based on the msg entered by the user. If the record exists, update the specified record value. Otherwise, insert the specified record, and return the successfully operated record to the user through the parameter of the OnRecv method in cb by default.
* The user can determine whether it is an insert operation or update operation based on the record version. When version == 1 means that it is an insert operation, while version > 1 means that it is an update operation.
* The user can also set returning the data before the update through the parameters of the OnRecv method in cb when the operation succeeds through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_SUCCESS, "3").
* @note: the data before the update will only be returned when it is the actual update operation (that is, the record version in the callback function is greater than 1). Otherwise, the value passed into OnRecv callback function is the msg pointer to the user request.
* The user can also set returning the data before the update through the parameters of the OnError method in cb when the operation fails through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_FAIL, "3").
* @note: only when the result is TcapErrCode::SVR_ERR_FAIL_INVALID_VERSION or other error codes indicating that the record already exists before the operation, will the existing data be returned. Otherwise, the value passed into OnError callback function is the msg pointer to the user request.
* The user can also set returning the record when the operation succeeds or fails through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_SUCCESS, "0") or SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_FAIL, "0").
*
* @param [INOUT] msg: msg of the data record to be inserted or updated
* @param [IN] operation: additional operation that is executed based on the successful execution of the Set operation. The operation is an operation expression for an array, that is, a PUSH or POP operation.
* The PUSH expression is PUSH<repeated field># [0 | 1 |... | - 1] [<assign expr>]
* The POP expression is POP <repeated-field>#[<array-indexes>][condition-expr]
* For example, "PUSH lockid#[-1][$=2];", insert a field at the end of the array and assign a value of 2
* For example, "PUSH pay#[1][total_money=4.4,pay_times=4];", insert a combination type at the subscript 1 and assign a value to the field
* For example, "POP lockid#[0-3][$<=3];", delete elements with subscripts ranging from 0 to 3 that meet the condition lockid<=3
* @param [IN] condition: filter condition expression. The Set will only be executed if the condition is matched
* Currently only contains condition filtering is supported, and the expression is <repeated-field> contains(<condition-expr>)
* For example, "a.b.c contains ($>0)", where a.b.c is a basic type, and '$' is the field value
* For example, "a.b.c contains (x>0 AND y>0)", where a.b.c is a combination type, and 'x' is the basic field value in the combination type
* @param [INOUT] cb: message callback function
* @retval COMMON_ERR_CONDITION_NOT_MATCHED: condition is not matched, and the record will not be updated.
* @retval <0 failed and returned the corresponding error code.
* @retval = 0 operation successful.
*/
int Set(::google::protobuf::Message *msg, const std::string &operation, const std::string &condition, TcaplusPbCallback *cb);
/**
* @brief: insert the record based on the msg entered by the user, and return the successfully inserted record to the user through the parameters of the OnRecv method in cb by default. If the key exists, report an error and exit.
* The user can also set returning the existing data through the parameters of the OnError method in cb when the insert fails through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_FAIL, "3").
* @note: only when the result is TcapErrCode::SVR_ERR_FAIL_RECORD_EXIST or other error codes indicating that the record already exists before the operation, will the existing data be returned. Otherwise, the value passed into OnError callback function is the msg pointer to the user request.
* The user can also set not returning the record when the insert succeeds or fails through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_SUCCESS, "0") or SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_FAIL, "0").
*
* @param [INOUT] msg: msg of the data record to be inserted
* @param [INOUT] cb: message callback function
* @retval < 0 failed and returned the corresponding error code.
* @retval = 0 operation successful
*/
int Add(::google::protobuf::Message *msg, TcaplusPbCallback *cb);
/**
* @brief: increase the value of the field specified by msg based on the key value and values increment value in msg entered by the user and the field name specified by dottedpaths. The field is a numeric variable.
* @param [INOUT] msg: data record msg, containing the key value entered by the user, return the result value of the incremental field and update it to msg
* @param [IN] dottedpaths: dotted nested string set of the field name
* @param [INOUT] cb: message callback function
* @retval TXHDB_ERR_RECORD_NOT_EXIST: the record does not exist.
* @retval <0 failed and returned the corresponding error code. It means that there are no field updates.
* @retval 0 operation successful. It means that all fields have been updated successfully.
*/
int FieldInc(const std::set<std::string> &dottedpaths, ::google::protobuf::Message *msg, TcaplusPbCallback *cb);
/**
* @brief: increase the value of the specified field based on the key value and values increment value in msg entered by the user and the field name specified by dottedpaths. The field is a numeric variable
* @param [INOUT] msg: key value entered by the user, return the result value of the incremental field and update it to msg
* @param [IN] dottedpaths: dotted nested string of the field name
* @param [IN] lowerLimitDottedpaths: dotted nested string of the field name where the lower limit needs to be specified, If empty, the lower limit is not set
* @param [IN] lowerLimit: lower limit value of the field to be specified. If it is NULL, the lower limit is not set
* @param [IN] upperLimitDottedpaths: dotted nested string of the field name where the upper limit needs to be specified, If empty, the upper limit is not set
* @param [IN] upperLimit: upper limit value of the field to be specified. If it is NULL, the upper limit is not set
* @param [INOUT] cb: message callback function
* @retval TXHDB_ERR_RECORD_NOT_EXIST: the record does not exist.
* @retval <0 failed and returned the corresponding error code. It means that there are no field updates.
* @retval 0 operation successful. It means that all fields have been updated successfully.
*/
int FieldInc(const std::set<std::string> &dottedpaths,
::google::protobuf::Message *msg,
const std::set<std::string> &lowerLimitDottedpaths,
::google::protobuf::Message *lowerLimit,
const std::set<std::string> &upperLimitDottedpaths,
::google::protobuf::Message *upperLimit,
TcaplusPbCallback *cb);
/**
* @brief: increase the value of the field specified by msg based on the key value and values increment value in msg entered by the user and the field name specified by dottedpaths. The field is a numeric variable.
* @param [INOUT] msg: data record msg, containing the key value entered by the user, return the result value of the incremental field and update it to msg
* @param [IN] dottedpaths: dotted nested string set of the field name
* @param [IN] operation: additional operation that is executed based on the successful execution of the FieldInc operation. The operation is an operation expression for an array, that is, a PUSH or POP operation
* The PUSH expression is PUSH<repeated field># [0 | 1 |... | - 1] [<assign expr>]
* The POP expression is POP <repeated-field>#[<array-indexes>][condition-expr]
* For example, "PUSH lockid#[-1][$=2];", insert a field at the end of the array and assign a value of 2
* For example, "PUSH pay#[1][total_money=4.4,pay_times=4];", insert a combination type at the subscript 1 and assign a value to the field
* For example, "POP lockid#[0-3][$<=3];", delete elements with subscripts ranging from 0 to 3 that meet the condition lockid<=3
* @param [IN] condition: filter condition expression. The modification operation will only be executed if the condition is matched
* Currently only contains condition filtering is supported, and the expression is <repeated-field> contains(<condition-expr>)
* For example, "a.b.c contains ($>0)", where a.b.c is a basic type, and '$' is the field value
* For example, "a.b.c contains (x>0 AND y>0)", where a.b.c is a combination type, and 'x' is the basic field value in the combination type
* @param [INOUT] cb: message callback function
* @retval TXHDB_ERR_RECORD_NOT_EXIST: the record does not exist.
* @retval COMMON_ERR_CONDITION_NOT_MATCHED: condition is not matched, and no fields need to be updated.
* @retval <0 failed and returned the corresponding error code. It means that there are no field updates.
* @retval 0 operation successful. It means that all fields have been updated successfully.
*/
int FieldInc(const std::set<std::string> &dottedpaths, ::google::protobuf::Message *msg,
const std::string &operation, const std::string &condition,
TcaplusPbCallback *cb);
/**
* @brief: increase the value of the specified field based on the key value and values increment value in msg entered by the user and the field name specified by dottedpaths. The field is a numeric variable
* @param [INOUT] msg: key value entered by the user, return the result value of the incremental field and update it to msg
* @param [IN] dottedpaths: dotted nested string of the field name
* @param [IN] lowerLimitDottedpaths: dotted nested string of the field name where the lower limit needs to be specified, If empty, the lower limit is not set
* @param [IN] lowerLimit: lower limit value of the field to be specified. If it is NULL, the lower limit is not set
* @param [IN] upperLimitDottedpaths: dotted nested string of the field name where the upper limit needs to be specified, If empty, the upper limit is not set
* @param [IN] upperLimit: upper limit value of the field to be specified. If it is NULL, the upper limit is not set
* @param [IN] operation: additional operation that is executed based on the successful execution of the FieldInc operation. The operation is an operation expression for an array, that is, a PUSH or POP operation
* The PUSH expression is PUSH<repeated field># [0 | 1 |... | - 1] [<assign expr>]
* The POP expression is POP <repeated-field>#[<array-indexes>][condition-expr]
* For example, "PUSH lockid#[-1][$=2];", insert a field at the end of the array and assign a value of 2
* For example, "PUSH pay#[1][total_money=4.4,pay_times=4];", insert a combination type at the subscript 1 and assign a value to the field
* For example, "POP lockid#[0-3][$<=3];", delete elements with subscripts ranging from 0 to 3 that meet the condition lockid<=3
* @param [IN] condition: filter condition expression. The modification operation will only be executed if the condition is matched
* Currently only contains condition filtering is supported, and the expression is <repeated-field> contains(<condition-expr>)
* For example, "a.b.c contains ($>0)", where a.b.c is a basic type, and '$' is the field value
* For example, "a.b.c contains (x>0 AND y>0)", where a.b.c is a combination type, and 'x' is the basic field value in the combination type
* @param [INOUT] cb: message callback function
* @retval TXHDB_ERR_RECORD_NOT_EXIST: the record does not exist.
* @retval COMMON_ERR_CONDITION_NOT_MATCHED: condition is not matched, and no fields need to be updated.
* @retval <0 failed and returned the corresponding error code. It means that there are no field updates.
* @retval 0 operation successful. It means that all fields have been updated successfully.
*/
int FieldInc(const std::set<std::string> &dottedpaths,
::google::protobuf::Message *msg,
const std::set<std::string> &lowerLimitDottedpaths,
::google::protobuf::Message *lowerLimit,
const std::set<std::string> &upperLimitDottedpaths,
::google::protobuf::Message *upperLimit,
const std::string &operation,
const std::string &condition,
TcaplusPbCallback *cb);
/**
* @brief: update the value of the field specified by msg based on the key value in msg entered by the user and the field name specified by dottedpaths. Values that do not exist on the server will be appended.
*
* @param [IN] msg: data record msg, containing the key value entered by the user, and return the specified field to msg
* @param [IN] dottedpaths: dotted nested string set of the field name
* @retval TXHDB_ERR_RECORD_NOT_EXIST: the record does not exist.
* @retval <0 failed and returned the corresponding error code. It means that there are no field updates.
* @retval 0 operation successful. It means that all fields have been updated successfully.
*/
int FieldSet(const std::set<std::string> &dottedpaths, ::google::protobuf::Message *msg, TcaplusPbCallback *cb);
/**
* @brief: update the value of the field specified by msg based on the key value in msg entered by the user and the field name specified by dottedpaths. Values that do not exist on the server will be appended.
*
* @param [IN] msg: data record msg, containing the key value entered by the user, and return the specified field to msg
* @param [IN] dottedpaths: dotted nested string set of the field name
* @param [IN] operation: additional operation that is executed based on the successful execution of the FieldSet operation. The operation is an operation expression for an array, that is, a PUSH or POP operation
* The PUSH expression is PUSH<repeated field># [0 | 1 |... | - 1] [<assign expr>]
* The POP expression is POP <repeated-field>#[<array-indexes>][condition-expr]
* For example, "PUSH lockid#[-1][$=2];", insert a field at the end of the array and assign a value of 2
* For example, "PUSH pay#[1][total_money=4.4,pay_times=4];", insert a combination type at the subscript 1 and assign a value to the field
* For example, "POP lockid#[0-3][$<=3];", delete elements with subscripts ranging from 0 to 3 that meet the condition lockid<=3
* @param [IN] condition: filter condition. The FieldSet operation will only be executed if the condition is matched.
* Currently only contains condition filtering is supported, and the expression is <repeated-field> contains(<condition-expr>)
* For example, "a.b.c contains ($>0)", where a.b.c is a basic type, and '$' is the field value
* For example, "a.b.c contains (x>0 AND y>0)", where a.b.c is a combination type, and 'x' is the basic field value in the combination type
* @retval TXHDB_ERR_RECORD_NOT_EXIST: the record does not exist.
* @retval COMMON_ERR_CONDITION_NOT_MATCHED: condition is not matched, and no fields need to be updated.
* @retval <0 failed and returned the corresponding error code. It means that there are no field updates.
* @retval 0 operation successful. It means that all fields have been updated successfully.
*/
int FieldSet(const std::set<std::string> &dottedpaths, ::google::protobuf::Message *msg,
const std::string &operation, const std::string &condition,
TcaplusPbCallback *cb);
/**
* @brief: get the value of the specified field based on the key value in msg entered by the user and the field name specified by dottedpaths, and fill it to msg.
*
* @param [IN] dottedpaths: dotted nested string set of the field name
* @param [INOUT] msg: data record msg, containing the key value entered by the user, and return the specified field to msg
* @param [IN] dottedpaths: dotted nested string set of the field name
* @param [INOUT] cb: message callback function
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful. Only when at least one field is successfully queried will it return 0.
*/
int FieldGet(const std::set<std::string> &dottedpaths, ::google::protobuf::Message *msg, TcaplusPbCallback *cb);
/**
* @brief: get the value of the specified field based on the key value in msg entered by the user and the field name specified by dottedpaths, and fill it to msg.
*
* @param [IN] dottedpaths: dotted nested string set of the field name
* @param [INOUT] msg: data record msg, containing the key value entered by the user, and return the specified field to msg
* @param [IN] condition: filter condition of the record
* @param [INOUT] cb: message callback function
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful. Only when at least one field is successfully queried will it return 0.
*/
int FieldGet(const std::set<std::string> &dottedpaths, ::google::protobuf::Message *msg, const std::string &condition, TcaplusPbCallback *cb);
/**
* @brief: get the value of the specified field based on the key value in the msg of the req entered by the user and the field name specified by dottedpaths, and fill it to cb.
*
* @param [INOUT] req: data record msg, containing the key value entered by the user, and return the specified field to msg
* @param [OUT] cb: return the dotted nested string set of the field name that failed to find
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful. Only when at least one field is successfully queried will it return 0.
*/
int FieldGet(NS_TCAPLUS_PROTOBUF_API::BatchFieldGetRequest &req, TcaplusPbCallback *cb);
/**
* @brief: query the record using the expression described by query and return part data value of the record. Only array query is supported
*
* @param [INOUT] msg: data record msg, which contains the primary key value when used as input, and contains the returned result data when used as output
* Note: the returned msg will be merged with the input msg, that is, the interface calls Message::MergeFrom internally
* @param [IN] query: query state, syntax:
* query ::=
* GET repeated_field [ #\[ index_range [, index_range]* \] ] [ \[ inner_condition \] ]
* index_range ::=
* number [ - number ]
* Where the number range is -1 to INT_MAX, -1 means the last position of the array
* For example, GET mail_list #[1-9][domain=="qq.com"]
* @param [IN] queryOption: for query option settings, see NS_TCAPLUS_PROTOBUF_API::TcaplusQueryOption
* @param [IN] condition: record level filter condition. The query operation will only be executed if the condition is matched. If =="", no filtering will be executed.
* @param [INOUT] cb: message callback function
* @retval TXHDB_ERR_RECORD_NOT_EXIST: the record does not exist.
* @retval COMMON_ERR_CONDITION_NOT_MATCHED: condition is not matched.
* @retval <0 failed and returned the corresponding error code. It means that there are no field updates.
* @retval 0 operation successful. It means that all fields have been updated successfully.
*/
int Query(::google::protobuf::Message *msg, const std::string &query, int queryOption,
const std::string &condition, TcaplusPbCallback *cb);
/**
* @brief: operate the array through the expression described by operation, and return the successfully updated record to the user through the parameter of the OnRecv method in cb by default.
* The user can also set returning the data before the update through the parameters of the OnRecv method in cb when the update succeeds through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_SUCCESS, "3").
* The user can also set returning the data before the update through the parameters of the OnError method in cb when the update fails through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_FAIL, "3").
* @note: only when the result is TcapErrCode::SVR_ERR_FAIL_INVALID_VERSION or other error codes indicating that the record already exists before the operation, will the data before the update be returned. Otherwise, the value passed into OnError callback function is the msg pointer to the user request.
* The user can also set not return the record when the update succeeds or fails through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_SUCCESS, "0") or SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_FAIL, "0").
*
* @param [INOUT] msg: data record containing the key value entered by the user
* @param [IN] operation: operation expression for an array, that is, PUSH or POP operation
* The PUSH expression is PUSH<repeated field># [0 | 1 |... | - 1] [<assign expr>]
* The POP expression is POP <repeated-field>#[<array-indexes>][condition-expr]
* For example, "PUSH lockid#[-1][$=2];", insert a field at the end of the array and assign a value of 2
* For example, "PUSH pay#[1][total_money=4.4,pay_times=4];", insert a combination type at the subscript 1 and assign a value to the field
* For example, "POP lockid#[0-3][$<=3];", delete elements with subscripts ranging from 0 to 3 that meet the condition lockid<=3
* @param [IN] condition: filter condition. The UpdateItem operation will only be executed if the condition is matched.
* Currently only contains condition filtering is supported, and the expression is <repeated-field> contains(<condition-expr>)
* For example, "a.b.c contains ($>0)", where a.b.c is a basic type, and '$' is the field value
* For example, "a.b.c contains (x>0 AND y>0)", where a.b.c is a combination type, and 'x' is the basic field value in the combination type
* @param [INOUT] cb: message callback function
* @retval TXHDB_ERR_RECORD_NOT_EXIST: the record does not exist.
* @retval COMMON_ERR_CONDITION_NOT_MATCHED: condition is not matched, and no fields need to be updated.
* @retval <0 failed and returned the corresponding error code. It means that there are no field updates.
* @retval = 0 operation successful. It means that all fields have been updated successfully.
*/
int UpdateItem(::google::protobuf::Message *msg, const std::string &operation, const std::string &condition, TcaplusPbCallback *cb);
/**
* @brief: get the specified field values of all the records in the List table based on the key value in the msg of the req entered by the user and the field name specified by dottedpaths, and fill it to cb.
*
* @param [INOUT] req: data record msg, containing the key value entered by the user, and return the specified field to msg
* @param [OUT] cb: return the dotted nested string set of the field name that failed to find
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful. Only when at least one field is successfully queried will it return 0.
*/
int ListGetAll(NS_TCAPLUS_PROTOBUF_API::ListGetAllRequest &req, TcaplusPbCallback *cb);
/**
* @brief: delete the record corresponding to the index of the key value in the List table based on the key value in the msg of the req entered by the user, and fill in the cb with the successfully deleted record by default. The key of the ListBatchDeleteResponse.m_mapMsg is the index of the successfully deleted record, and the value is the msg pointer.
* The user can also set not returning the data when the deletion succeeds through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_SUCCESS, "0"). If so, the key of ListBatchDeleteResponse.m_mapMsg in cb is the index of the successfully deleted record, and the value is a null pointer.
*
* @param [INOUT] req: msg of the data record to be deleted
* @param [OUT] cb: the ListBatchDeleteResponse is used to receive request execution results
* @retval < 0 failed and returned the corresponding error code.
*@retval = 0: operation successful and returned 0 with at least one record successfully deleted
*/
int ListBatchDel(NS_TCAPLUS_PROTOBUF_API::ListBatchDeleteRequest &req, TcaplusPbCallback *cb);
/**
* @brief: add a record after the specified position in the List table based on the msg of the req entered by the user, and fill in the ListAddAfterResponse.m_nElemIndex with the subscript of the successfully inserted record by default. The ListAddAfterResponse.m_mapMsg is empty.
* The user can also set returning the latest data when the insert succeeds through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_SUCCESS, "2"). If so, the key of ListAddAfterResponse.m_mapMsg is the index of the successfully inserted or expired record, and value is the msg pointer to the corresponding record.
*
* @param [INOUT] req msg of the data record to be inserted
* @param [OUT] cb: the ListAddAfterResponse is used to receive request execution results
* @retval < 0 failed and returned the corresponding error code.
* @retval = 0 operation successful
*/
int ListAddAfter(NS_TCAPLUS_PROTOBUF_API::ListAddAfterRequest &req, TcaplusPbCallback *cb);
/**
* @brief: update the record at the specified location in the List table based on the msg of the req entered by the user, and fill in the cb with the successfully updated record by default. The ListReplaceResponse.m_pMsg is the pointer to the updated record.
* The user can also set returning the data before the operation when the update succeeds through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_SUCCESS, "3"). If so, the ListReplaceResponse.m_pMsg in cb is the pointer to the record before the update.
* The user can also set returning the data before the operation when the update fails through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_FAIL, "3"). If so, he ListReplaceResponse.m_pMsg in cb is a null pointer, and the value passed into OnError callback function is the pointer to the record before the operation.
* @note: only when the result is TcapErrCode::SVR_ERR_FAIL_INVALID_VERSION or other error codes indicating that the record already exists before the operation, will the existing data be returned. Otherwise, the value passed into OnError callback function is the msg pointer to the user request.
* The user can also set not returning the record when the update succeeds or fails through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_SUCCESS, "0") or SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_FAIL, "0"). If so, the ListReplaceResponse.m_pMsg is empty.
*
* @param [INOUT] req: msg and index of the data record to be updated
* @param [OUT] cb: the ListReplaceResponse is used to receive request execution results
* @retval < 0 failed and returned the corresponding error code.
* @retval = 0 operation successful
*/
int ListReplace(NS_TCAPLUS_PROTOBUF_API::ListReplaceRequest &req, TcaplusPbCallback *cb);
/**
* @brief: operate the array through the expression described by operation, and full the successfully updated record into cb by default. The ListUpdateItemResponse.m_pMsg is the pointer to the updated record.
* The user can also set returning the data before the operation through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_SUCCESS, "3"). If so, the ListUpdateItemResponse.m_pMsg in the cb is the pointer to the record before the update.
* The user can also set returning the data before the operation when the update fails through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_FAIL, "3"). If so, the ListUpdateItemResponse.m_pMsg in cb is a null pointer, and the value passed into OnError callback function is the pointer to the record before the operation.
* @note: only when the result is TcapErrCode::SVR_ERR_FAIL_INVALID_VERSION or other error codes indicating that the record already exists before the operation, will the existing data be returned. Otherwise, the value passed into OnError callback function is the msg pointer to the user request.
* The user can also set returning the record when the update succeeds or fails through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_SUCCESS, "0") or SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_FAIL, "0"). If so, the ListUpdateItemResponse.m_pMsg is empty.
*
* @param [IN] req: operation request, including msg, operation expression, and conditional filter expression
* @param [OUT] cb: the ListUpdateItemResponse is used to receive request execution results
* @retval < 0 failed and returned the corresponding error code.
* @retval = 0 operation successful
*/
int ListUpdateItem(NS_TCAPLUS_PROTOBUF_API::ListUpdateItemRequest &req, TcaplusPbCallback *cb);
/**
* @brief: query the record using the expression described by query and return part data value of the record. Only array query is supported
*
* @param [INOUT] msg: data record msg, which contains the primary key value when used as input, and contains the returned result data when used as output
* @param [IN] req: query request, including msg, query expression, and conditional filter expression
* @param [OUT] cb: callback
* @retval TXHDB_ERR_RECORD_NOT_EXIST: the record does not exist.
* @retval COMMON_ERR_CONDITION_NOT_MATCHED: condition is not matched.
* @retval <0 failed and returned the corresponding error code. It means that there are no field updates.
* @retval 0 operation successful. It means that all fields have been updated successfully.
*/
int ListQuery(NS_TCAPLUS_PROTOBUF_API::ListQueryRequest &req, TcaplusPbCallback *cb);
/**
* @brief: delete all records of the specified key in the List table based on the key value in the msg of the req entered by the user, and fill it to cb.
*
* @param [INOUT] req: data record msg, containing the key value entered by the user, and return the specified field to msg
* @param [OUT] cb: return the dotted nested string set of the field name that failed to find
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful. Only when at least one field is successfully queried will it return 0.
*/
int ListDelAll(NS_TCAPLUS_PROTOBUF_API::ListDelAllRequest &req, TcaplusPbCallback *cb);
/**
* @brief: get the specified subscript record of the specified key in the List table based on the key value in the msg of the req entered by the user and fill it to cb.
*
* @param [INOUT] req: data record msg, containing the key value entered by the user, and return the specified field to msg
* @param [OUT] cb: return the dotted nested string set of the field name that failed to find
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful. Only when at least one field is successfully queried will it return 0.
*/
int ListGet(NS_TCAPLUS_PROTOBUF_API::ListGetRequest &req, TcaplusPbCallback *cb);
/**
* @brief: delete the record at the specified position in the List table based on the msg of the req entered by the user, and fill the previous record into the cb by default when the deletion is successful. The ListDeleteResponse.m_nElemIndex is the index of the successfully deleted record, and the m_pMsg is the msg pointer.
* The user can also set returning the data before the operation when the deletion fails through SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_FAIL, "3"). If so, the ListDeleteResponse.m_pMsg in cb is a null pointer, and the value passed into OnError callback function is the pointer to the record before the operation.
* @note: only when the result is TcapErrCode::SVR_ERR_FAIL_INVALID_VERSION or other error codes indicating that the record already exists before the operation, will the existing data be returned. Otherwise, the value passed into OnError callback function is the msg pointer to the user request.
* The user can also set SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_SUCCESS, "0") or SetMessageOption(msg, MESSAGE_OPTION_RESULT_FLAG_FOR_FAIL, "0") to set not to return records when the deletion succeeds or fails.
*
* @param [INOUT] req: msg and index of the data record to be deleted
* @param [OUT] cb: the ListDeleteResponse is used to receive request execution results
* @retval < 0 failed and returned the corresponding error code.
* @retval = 0 operation successful
*/
int ListDel(NS_TCAPLUS_PROTOBUF_API::ListDeleteRequest &req, TcaplusPbCallback *cb);
/**
* @brief: traverse all records in the List table based on the information specified by the req entered by the user and fill it to cb.
*
* @param [INOUT] req: data record msg, containing the key value entered by the user, and return the specified field to msg
* @param [OUT] cb: return the dotted nested string set of the field name that failed to find
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful. Only when at least one field is successfully queried will it return 0.
*/
int ListTraverse(NS_TCAPLUS_PROTOBUF_API::ListTraverseRequest &req, TcaplusPbCallback *cb);
/**
* @brief: traverse the table, and fill the message into the msg
*
* @param [INOUT] msg: return the specified field to msg
*@param [IN] condition: filter condition
* @param [INOUT] cb: callback function
* @retval <0 failed and returned the corresponding error code.
* @retval 0 traversal successful.
*/
int Traverse(::google::protobuf::Message *msg, const std::string &condition, TcaplusPbCallback *cb);
/**
* @brief: traverse the table, and fill the message into the msg
*
* @param [INOUT] msg: return the specified field to msg
* @param [INOUT] cb: callback function
* @retval <0 failed and returned the corresponding error code.
* @retval 0 traversal successful.
*/
int Traverse(::google::protobuf::Message *msg, TcaplusPbCallback *cb);
/**
* @brief: traverse the table, and fill the message into the msg
*
* @param [INOUT] msg: return the specified field to msg
*@param [IN] condition: filter condition
* @param [IN] dottedpaths dotted nested string set of the field name
* @param [INOUT] cb: callback function
* @retval <0 failed and returned the corresponding error code.
* @retval 0 traversal successful.
*/
int Traverse(::google::protobuf::Message *msg, const std::set<std::string> &dottedpaths, const std::string &condition, TcaplusPbCallback *cb);
/**
* @brief: set the TTL value of the corresponding record based on the key value in each msg of vecReq enered by the user.
*
* @param [IN] vecReq: each msg entered and the corresponding set TTL value, where the msg of SetTTLRequest contains the key value entered by the user
* @param [IN] cb: message callback function
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful.
*/
int SetTTL(const std::vector<NS_TCAPLUS_PROTOBUF_API::SetTTLRequest> &vecReq, TcaplusPbCallback *cb);
/**
* @brief: set the TTL value of the corresponding record based on the key value in msg of vecReq enered by the user.
*
* @param [IN] vecReq: msg entered and the corresponding set TTL value, where the msg of SetTTLRequest contains the key value entered by the user
* @param [IN] cb: message callback function
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful.
*/
int SetTTL(const NS_TCAPLUS_PROTOBUF_API::SetTTLRequest &req, TcaplusPbCallback *cb);
/**
* @brief: get the TTL value of the corresponding record based on the key value of each msg entered by the user.
*
* @param [IN] msg: list of msgs entered, and each msg contains the key value entered by the user
* @param [IN] cb: message callback function
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful.
*/
int GetTTL(const std::vector< ::google::protobuf::Message* > &msgs, TcaplusPbCallback *cb);
/**
* @brief: get the TTL value of the corresponding record based on the key value of the msg entered by the user.
*
* @param [IN] msgs: msg entered, containing the key value entered by the user
* @param [IN] cb: message callback function
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful.
*/
int GetTTL(::google::protobuf::Message *msg, TcaplusPbCallback *cb);
/**
* @brief: return the number of messages currently pending
*
* @brief: the number of messages currently pending
*/
size_t GetPendingCount() { return m_mapStatus.size();}
/**
* @brief: register the encryption suite
*
* @param [IN] suite: encryption suite
* @retval <0: failed, registration failed.
* @retval 0: create a coroutine and start it
*/
int RegisterCipherSuite(CipherSuite *suite);
/**
* @brief: cancel the encryption suite
*
* @param [IN] suite: encryption suite
* @retval <0: failed, cancellation failed.
* @retval 0 successful, cancellation successful
*/
int UnregisterCipherSuite(CipherSuite *suite);
/**
* @brief: return the number of records in the current table
*
* @param [IN] table_name: table name
* @param [OUT] cb: callback that returns the number of records
* @retval <0: failed
* @retval 0: successful
*/
int GetCount(const char* table_name, TcaplusPbCallback *cb);
/**
* @brief: delete the corresponding record based on the index value of the msg entered by the user.
*
* @param [INOUT] req: the req entered by the user
* @param [INOUT] res: the res entered by the user
* @param [INOUT] cb: message callback function
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful.
*/
int Del(NS_TCAPLUS_PROTOBUF_API::IndexDeleteRequest& req, TcaplusPbCallback *cb);
/**
* @brief: update the record based on the msg entered by the user, and return the successfully operated record to the user through the parameters of the OnRecv method in cb by default.
*
* @param [INOUT] msg: msg of the data record to be updated
* @param [INOUT] cb: message callback function
* @retval COMMON_ERR_CONDITION_NOT_MATCHED: condition is not matched, and the record will not be updated.
* @retval <0 failed and returned the corresponding error code.
* @retval = 0 operation successful.
*/
int Update(::google::protobuf::Message *msg, TcaplusPbCallback *cb);
/**
* @brief: update the record based on the msg entered by the user, and return the successfully operated record to the user through the parameters of the OnRecv method in cb by default.
*
* @param [INOUT] msg: msg of the data record to be updated
* @param [IN] operation: additional operation that is executed based on the successful execution of the Update operation. The operation is an operation expression for an array, that is, a PUSH or POP operation.
* The PUSH expression is PUSH<repeated field># [0 | 1 |... | - 1] [<assign expr>]
* The POP expression is POP <repeated-field>#[<array-indexes>][condition-expr]
* For example, "PUSH lockid#[-1][$=2];", insert a field at the end of the array and assign a value of 2
* For example, "PUSH pay#[1][total_money=4.4,pay_times=4];", insert a combination type at the subscript 1 and assign a value to the field
* For example, "POP lockid#[0-3][$<=3];", delete elements with subscripts ranging from 0 to 3 that meet the condition lockid<=3
* @param [IN] condition: filter condition expression. The Update will only be executed if the condition is matched
* Currently only contains condition filtering is supported, and the expression is <repeated-field> contains(<condition-expr>)
* For example, "a.b.c contains ($>0)", where a.b.c is a basic type, and '$' is the field value
* For example, "a.b.c contains (x>0 AND y>0)", where a.b.c is a combination type, and 'x' is the basic field value in the combination type
* @param [IN] resultFlag: set the return method for data.
* @param [INOUT] cb: message callback function
* @retval COMMON_ERR_CONDITION_NOT_MATCHED: condition is not matched, and the record will not be updated.
* @retval <0 failed and returned the corresponding error code.
* @retval = 0 operation successful.
*/
int Update(::google::protobuf::Message *msg, const std::string &operation, const std::string &condition, int resultFlag, TcaplusPbCallback *cb);
/**
* @brief: insert data in batch based on the msgs entered by the user
*
* @param [INOUT] msgs: msgs list entered by the user
* @param [IN] resultFlag: set the return method for data.
* @param [INOUT] cb: message callback function
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful. Only when at least one field is successfully queried will it return 0.
*/
int BatchAdd(std::vector< ::google::protobuf::Message * > *msgs, int resultFlag, TcaplusPbCallback *cb);
/**
* @brief: delete data in batch based on the msgs entered by the user
*
* @param [INOUT] msgs: msgs list of the data record to be deleted.
* @param [IN] resultFlag: set the return method for data.
* @param [INOUT] cb: message callback function
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful. Only when at least one field is successfully queried will it return 0.
*/
int BatchDelete(std::vector< ::google::protobuf::Message * > *msgs, int resultFlag, TcaplusPbCallback *cb);
/**
* @brief: update data in batch based on the msgs entered by the user
*
* @param [INOUT] msgs: msgs list of the data record to be updated.
* @param [IN] resultFlag: set the return method for data.
* @param [INOUT] cb: message callback function
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful. Only when at least one field is successfully queried will it return 0.
*/
int BatchUpdate(std::vector< ::google::protobuf::Message * > *msgs, int resultFlag, TcaplusPbCallback *cb);
/**
* @brief: replace data in batch based on the msgs entered by the user
*
* @param [INOUT] msgs: msgs list of the data record to be replaced.
* @param [IN] resultFlag: set the return method for data.
* @param [INOUT] cb: message callback function
* @retval <0 failed and returned the corresponding error code.
* @retval 0 operation successful. Only when at least one field is successfully queried will it return 0.
*/
int BatchSet(std::vector< ::google::protobuf::Message * > *msgs, int resultFlag, TcaplusPbCallback *cb);
/**
* @brief: get the record corresponding to the index of the key value in the List table based on the key value in the msg of the req entered by the user, and fill in the cb with the successfully queried record by default. The key of the ListBatchGetResponse.m_mapMsg is the record index that is successfully queried, and the value is the msg pointer. *
* @param [INOUT] req: msg of the data record to be deleted
* @param [OUT] cb: the ListBatchGetResponse is used to receive request execution results
* @retval < 0 failed and returned the corresponding error code.
* @retval =0 operation successful, and only when at least one field is successfully queried will it return 0
*/
int ListBatchGet(NS_TCAPLUS_PROTOBUF_API::ListBatchGetRequest &req, TcaplusPbCallback *cb);
/**
* @brief: insert the record backward or forward based on the msgs of the req entered by the user, and fill the successful record into the cb by default. The key of the ListBatchAddRequest.m_msgs is the msg pointer, and the value is the insertion method (- 2 forward insertion, - 1 backward insertion);
* ListBatchAddRequest.m_cShifFlag can set the list table expiration mode; the key of the ListBatchAddResponse.m_mapMsg is the record index that is successfully queried, and the value is the msg pointer. *
* @param [INOUT] req: msg of the data record to be deleted
* @param [OUT] cb: the ListBatchAddResponse is used to receive request execution results
* @retval < 0 failed and returned the corresponding error code.
* @retval =0 operation successful, and only when at least one field is successfully inserted will it return 0
*/
int ListBatchAdd(NS_TCAPLUS_PROTOBUF_API::ListBatchAddRequest &req, TcaplusPbCallback *cb);
/**
* @brief: update the record corresponding to the index of the key value in the List table based on the msgs of the req entered by the user, and fill in the cb with the successful record by default. The key of the ListBatchUpdateResponse.m_mapMsg is the record index that is successfully updated, and the value is the msg pointer. *
* @param [INOUT] req: msg of the data record to be updated
* @param [OUT] cb: the ListBatchUpdateResponse is used to receive request execution results
* @retval < 0 failed and returned the corresponding error code.
* @retval =0 operation successful, and only when at least one field is successfully queried will it return 0
*/
int ListBatchUpdate(NS_TCAPLUS_PROTOBUF_API::ListBatchUpdateRequest &req, TcaplusPbCallback *cb);
/**
* @brief: resource release operation that matches Init
*
*/
void Fini();
};
8. FAQ
For details, see Meaning and Handling of Error Codes.
8. Other Reference Documents
[[PB Generic Table] [Go SDK] Interface Description for Traversing Table Data](../../02Go_SDK/02Interface_Documents/16[Generic_Table]Traverse_Table_Data.md
[[PB Generic Table] [RESTFul API] Interface Description for Traversing Table Data](../../03RESTFul_API/02Interface_Documents/19[Generic_Table]Traverse_Table_Data.md